fix(api): render API reference from CRD/OpenAPI facts instead of guessing - #347
Open
youyongsong wants to merge 2 commits into
Open
fix(api): render API reference from CRD/OpenAPI facts instead of guessing#347youyongsong wants to merge 2 commits into
youyongsong wants to merge 2 commits into
Conversation
…sing
The API components ignored facts already present in the CRD/OpenAPI sources
and pushed the responsibility onto authors, who miss it. This fixes a family
of rendering defects and adds offline integrity tooling.
Correctness:
- derive `namespaced` from `spec.scope` (Cluster resources no longer render
an unreachable `/namespaces/{namespace}/` path); prop still overrides
- use `spec.names.plural` for endpoint paths instead of `pluralize(kind)`
(fixes hyphenated / irregular plurals); add a `plural` escape-hatch prop
- default multi-version CRDs to the version kubectl resolves (highest-priority
`served` version, never `served: false`), for both schema and endpoint
version sites; configurable via `api.crdVersion`
- render `/status` (and new `/scale`) from `subresources`, not from a `status`
property; fixes both fabricated and missing status endpoints
- render `x-kubernetes-int-or-string` (`anyOf`) types instead of an empty cell
- de-duplicate schema array-item anchors (`.spec.foo[]` vs `.spec.foo`) with a
page-level slugger; give summary-less operations a real id (no `#undefined`)
- read `requestBody.required` for the Request Body badge, not the body
schema's required-property list
Tooling / config:
- new `doom api check` command: offline validation of local CRD/OpenAPI sources
- new `no-unresolved-api-ref` lint rule for the five API components
- `api.references` object form `{ href, routePath?: string | false }`
(strings unchanged); `translate.copyOnlyDirectories`
- deterministic source ordering; `filepath`/`openapiPath` keys independent of
`process.cwd()`
- `<K8sPermissionTable>` shows a visible "not found" row instead of dropping it
- translate component chrome via `useTranslation` (en/zh/ru)
- surface top-level schema properties in the API-page outline
Includes fixture-docs regression fixtures for the CRD-scope / plural / version /
subresources / anchor / int-or-string cases (doom's own tekton fixtures cannot
trip them). See the changeset for downstream impact.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: fb22c26 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
commit: |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #347 +/- ##
==========================================
+ Coverage 54.27% 55.43% +1.15%
==========================================
Files 63 63
Lines 1555 1555
Branches 482 482
==========================================
+ Hits 844 862 +18
+ Misses 550 534 -16
+ Partials 161 159 -2 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
…al module Adds unit tests for the lines codecov flagged as uncovered in this PR: - `generateRuntimeModule` (utils/helpers.ts): deterministic sort of the map keys, and the map key staying relative to `root` (independent of `process.cwd()`) — the DOOM-17 / DOOM-19 fixes. - `apiPlugin.addRuntimeModules` (plugins/api/index.ts): the virtual module now carries `crdVersion` (and `pathPrefix` / `references`), and drops it when unset — the DOOM-4 escape hatch. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The API-reference components ignored facts already present in the CRD / OpenAPI sources and pushed the responsibility onto authors, who miss it. This fixes a family of rendering defects and adds offline integrity tooling. Full defect inventory + neutral review: this was tracked as DOOM-1..23 (18 actionable).
Correctness — read the source instead of guessing
namespacedderived fromspec.scope(Cluster resources no longer render an unreachable/namespaces/{namespace}/path); prop still overrides.spec.names.pluralinstead ofpluralize(kind)— fixes hyphenated (vpc-egress-gateways) and irregular (alaudaloadbalancer2) plurals; newpluralescape-hatch prop;toLocaleLowerCase→toLowerCase.kubectlresolves to (highest-priorityservedversion, neverserved: false), applied to both the schema and the endpoint path; configurable viaapi.crdVersion./status(and new/scale) rendered fromspec.versions[].subresources, not from astatusproperty — fixes both fabricated and missing status endpoints.x-kubernetes-int-or-string(anyOf) fields render their type instead of an empty cell.Anchors & badges
.spec.foo[]) no longer collide with the parent (.spec.foo) on the same HTML id (page-level stateful slugger).summaryno longer produceid="undefined"/ bare numeric anchors.requestBody.required(boolean), not the body schema's required-property list.New config & tooling
doom api check— offline validation of local CRD/OpenAPI sources (parse, kind, unique name,<group>_<plural>.yamlfilename convention, cross-file OpenAPI definition conflicts).no-unresolved-api-reflint rule for the five API components.api.referencesobject form{ href, routePath?: string | false }(strings unchanged);translate.copyOnlyDirectories.filepath/openapiPathkeys independent ofprocess.cwd().<K8sPermissionTable>shows a visible "not found" row instead of dropping it.useTranslation(en/zh/ru).Testing
yarn build(tsc) ✅ ·yarn test380 passed ✅fixture-docsregression fixtures (Cluster scope / hyphenated + irregular plural /served:falseversion / no-status-subresource / IntOrString / summary-less OpenAPIPath). doom's own tekton fixtures are 8/8 Namespaced, pluralize-compatible, single-version, 0 subresources — they structurally cannot trip these bugs.#undefinedanchors go to zero.🤖 Generated with Claude Code